/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.handlers.events;

import android.view.View;

import com.hercules.android.receiver.AndroidReceiver;
import com.hercules.android.receiver.model.objects.XREView;

/**
 * <p>
 * This interface defines the contract for binding Android listeners to Android view objects for various kinds of
 * events, such as keyboard, mouse, and view activation events
 * </p>
 *
 * <p>
 * <strong>Thread safety: </strong> The implementation of this interface must be thread-safe after initialization.
 * </p>
 *
 * @author mekanizumu, jaindsonvs
 * @version 1.0
 */
public interface EventListenerBinder {
    /**
     * <p>
     * Bind a key event listener to an Android view.
     * </p>
     *
     * @param xreView
     *            the XRE view that is the source of the possible event
     * @param receiver
     *            the receiver that will be used by the listener
     * @param keyEventType
     *            the key event type to bind.
     * @param uiView
     *            the Android view where the event actually comes from
     * @throws EventListenerBindingException
     *             if any error occurs
     * @throws IllegalArgumentException
     *             if keyEventType doesn't conform to the following legal value specification: Can't be null or empty
     *             and must be one of the constant string defined on XREKeyboardEvent. Or xreView is null; Or uiView is
     *             null; Or receiver is null;
     */
    public void bindKeyEventListener(String keyEventType, XREView xreView, View uiView, AndroidReceiver receiver)
        throws EventListenerBindingException;

    /**
     * <p>
     * Bind a mouse event listener to an Android view.
     * </p>
     *
     * @param xreView
     *            the XRE view that is the source of the possible event
     * @param receiver
     *            the receiver that will be used by the listener.
     * @param mouseEventType
     *            the mouse event type to bind.
     * @param uiView
     *            the Android view where the event actually comes from.
     * @throws EventListenerBindingException
     *             if any error occurs.
     * @throws IllegalArgumentException
     *             if mouseEventType doesn't conform to the following legal value specification: Can't be null or empty
     *             and must be one of the constant string defined on XREMouseEvent. Or xreView is null; Or uiView is
     *             null; Or receiver is null;
     */
    public void bindMouseEventListener(String mouseEventType, XREView xreView, View uiView, AndroidReceiver receiver)
        throws EventListenerBindingException;

    /**
     * <p>
     * Bind a view activation event listener to an Android view.
     * <p>
     *
     *
     * @param xreView
     *            the XRE view that is the source of the possible event.
     * @param receiver
     *            the receiver that will be used by the listener.
     * @param viewActivationEventType
     *            the view activation event type to bind.
     * @param uiView
     *            the Android view where the event actually comes from.
     * @throws EventListenerBindingException
     *             if any error occurs.
     * @throws IllegalArgumentException
     *             if viewActivationEventType doesn't conform to the following legal value specification: Can't be null
     *             or empty and must be one of the constant string defined on XREActivateViewEvent. Or xreView is null;
     *             Or uiView is null; Or receiver is null;
     */
    public void bindViewActivationEventListener(String viewActivationEventType, XREView xreView, View uiView,
            AndroidReceiver receiver) throws EventListenerBindingException;
}
